---
title: Mux & Astro
description: Mux를 사용하여 Astro에 고성능 동영상 추가하기
sidebar:
  label: Mux
type: media
logo: mux
stub: true
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

[Mux](https://www.mux.com?utm_campaign=21819274-Astro&utm_source=astro-docs)는 모든 규모의 기업을 위한 비디오 스트리밍 인프라 및 성능 분석을 제공하는 미디어 호스팅 서비스입니다.

Mux를 사용하여 동영상 콘텐츠를 저장하고 호스팅하면, [Mux Player](#mux-player)용 Astro 네이티브 동영상 컴포넌트, Astro 프로젝트에 Mux 동영상을 추가하기 위한 드롭인 컴포넌트, 웹사이트에서 Mux로 동영상을 업로드하기 위한 [Mux Uploader](#mux-uploader)를 이용할 수 있습니다. 이러한 컴포넌트는 [Mux Data](https://www.mux.com/docs/guides/data?utm_campaign=21819274-Astro&utm_source=astro-docs)와 원활하게 통합되어 동영상 참여도와 성과를 추적합니다.

[Mux Node SDK](#mux-node-sdk)를 통해 콘텐츠와 상호작용할 수도 있습니다.

:::tip
[Astro에서 동영상을 사용하기 위한 Mux의 전용 페이지](https://www.mux.com/video-for/astro?utm_campaign=21819274-Astro&utm_source=astro-docs)에서 비디오 임베딩, 저장, 스트리밍, 사용자 정의와 같은 기능에 대해 자세히 알아보세요!
:::

## Astro에서 Mux 사용하기

Mux의 API와 웹 컴포넌트는 Astro에서 작동하여 웹용 동영상과 스트림을 압축하고 최적화하며, 네트워크 상태에 따라 동영상 품질을 조정하고, 자막, 썸네일, 분석과 같은 추가 기능을 통합합니다. [Mux Node SDK](https://www.mux.com/docs/integrations/mux-node-sdk?utm_campaign=21819274-Astro&utm_source=astro-docs)는 Mux Data와 Mux Video API를 모두 지원합니다.

## 전제 조건

- 기존 Astro 프로젝트. 일부 기능을 사용하기 위해 [요청 시 렌더링](/ko/guides/on-demand-rendering/)을 위한 어댑터를 추가로 설치해야 할 수도 있습니다.
- Mux 계정. 계정이 없는 경우, `ASTRO` 코드를 사용하여 [Mux에 가입](https://dashboard.mux.com/login?utm_campaign=21819274-Astro&utm_source=astro-docs)하면 50달러의 크레딧을 받을 수 있습니다.

## Mux Player

Astro에서는, 최적화되고 반응성이 뛰어난 동영상 재생 및 라이브 스트리밍을 위한 모든 기능을 갖춘 [Mux Player](https://www.mux.com/docs/guides/mux-player-web?utm_campaign=21819274-Astro&utm_source=astro-docs)를 Astro의 네이티브 컴포넌트로 사용할 수 있습니다.

Mux Player는 비디오 플레이어 크기와 스트림 유형에 기반한 반응형 UI, 자동 썸네일 미리보기 및 포스터 이미지, 그리고 현대적인 비디오 플레이어 기능 (예: 전체 화면, PIP( 화면 속 화면), Chromecast, AirPlay)을 제공합니다.

```astro title="src/components/MyMuxVideoPlayer.astro"
---
import { MuxPlayer } from "@mux/mux-player-astro";
---
<MuxPlayer
  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
  metadata={{ video_title: 'Astro 동영상' }}
/>

```

Mux Player는 Mux Data의 분석 기능을 기본적으로 지원합니다. 배포된 사이트에서 동영상을 조회하면 대시보드에 방문자 참여도와 동영상 품질 지표가 표시됩니다.

### 설치하기

선호하는 패키지 관리자를 사용하여 Mux Player의 Astro 버전을 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @mux/mux-player-astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @mux/mux-player-astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @mux/mux-player-astro
  ```
  </Fragment>
</PackageManagerTabs>

Astro 프로젝트에서 Mux Player를 다음과 같이 사용할 수도 있습니다.

- 웹 컴포넌트 (`@mux/mux-player`의 `<mux-player>`)
- React 컴포넌트 (`@mux/mux-player-react`의 `<MuxPlayer />`)
- HTML 웹 임베드 (`<iframe>`)

### Mux에서 동영상 재생하기

다른 Astro 컴포넌트와 마찬가지로, 네이티브 `<MuxPlayer />` Astro 컴포넌트를 `.astro` 파일에 직접 가져와 사용하세요.

해당 자산의 `playbackId`가 필요합니다. 이는 Mux 대시보드에서 확인하거나 [해당 자산의 `ASSET_ID`를 통해 조회](#자산-데이터-조회하기)할 수 있습니다.

[Mux 웹 플레이어를 제어하는 다른 모든 옵션](https://www.mux.com/docs/guides/player-api-reference/?utm_campaign=21819274-Astro&utm_source=astro-docs) (예: 컨트롤 표시/숨기기, 스타일 요소, 쿠키 비활성화)은 선택 사항입니다.

```astro title="src/components/StarlightVideo.astro"
<MuxPlayer
  playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata={{
    video_title: 'Astro의 Starlight',
  }}
  style={{
    display: 'block',
    aspectRatio: '16/9',
    backgroundColor: '#000',
    margin: '1rem 0 2rem',
  }}
  primaryColor="#f2ec3a"
  secondaryColor="#0caa09"
  accentColor="#6e1e99"
  defaultShowRemainingTime={true}
/>
```

`playbackId`가 사전 녹화된 주문형 비디오가 아닌 라이브 스트림에 속하는 경우, [DVR 모드](https://www.mux.com/docs/guides/stream-recordings-of-live-streams#dvr-mode-vs-non-dvr-mode?utm_campaign=21819274-Astro&utm_source=astro-docs) 활성화 여부와 같은 옵션으로 Mux Player를 사용자 정의할 수 있습니다.

```astro
<MuxPlayer
  playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata={{
    video_title: 'Astro의 Starlight 스트림',
  }}
  streamType="live:dvr"
/>

```

모든 라이브 스트림은 향후 요청 시 재생할 수 있도록 Mux에 동영상 자산으로 녹화 및 저장됩니다.

## Mux 비디오 요소

[Mux 비디오 요소](https://www.mux.com/docs/guides/play-your-videos#mux-video-element?utm_campaign=21819274-Astro&utm_source=astro-docs)는 HTML5 `<video>` 요소를 대체하는 드롭인 대체 요소로, HLS 재생에 대한 브라우저 지원을 제공하며 방문자 및 성능 지표를 표시하도록 Mux Data가 자동으로 구성됩니다. [Mux Player](#mux-player)의 모든 기능이 필요하지 않거나 원하지 않을 때 사용하세요.

`<mux-video>` 웹 컴포넌트를 사용하려면 먼저 선호하는 패키지 관리자를 사용하여 `mux-video`를 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @mux/mux-video
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @mux/mux-video
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @mux/mux-video
  ```
  </Fragment>
</PackageManagerTabs>

그러면 `.astro` 파일의 `<script>` 태그에서 웹 컴포넌트를 가져와 렌더링할 수 있습니다.

동영상 자산의 `playback-id`가 필요합니다. 이는 Mux 대시보드에서 확인하거나 [해당 자산의 `ASSET_ID`를 통해 조회](#자산-데이터-조회하기)할 수 있습니다.

HTML5 `<video>` 요소의 모든 속성 (예: `poster`, `controls`, `muted`)은 물론, Mux 비디오 플레이어 컨트롤 (예: 메타데이터 제공, 해상도 제어, 쿠키 비활성화)도 사용할 수 있습니다.

```astro title="src/components/StarlightVideo.astro"
<script>import '@mux/mux-video'</script>

<mux-video
  playback-id="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata-video-title="Astro의 Starlight"
  controls
  disable-tracking
></mux-video>
```

## Mux Node SDK

[Mux Node SDK](https://www.mux.com/docs/integrations/mux-node-sdk?utm_campaign=21819274-Astro&utm_source=astro-docs)는 서버 측 TypeScript 또는 JavaScript에 Mux REST API에 대한 인증된 액세스를 제공합니다. 이를 통해 `.astro` 파일의 컴포넌트 스크립트에서 Mux 자산 및 데이터와 상호작용할 수 있습니다.

Mux Player 및 Mux Video 컴포넌트는 인증이 필요하지 않으며, `playbackId`만 있으면 공개적으로 접근 가능한 모든 동영상을 재생할 수 있습니다. 그러나 Node SDK를 통해 호스팅된 Mux 데이터에 연결하려면 [Mux API 액세스 토큰](#mux-환경-api-액세스)이 필요합니다.

### 설치하기

선호하는 패키지 관리자를 사용하여 Mux Node SDK를 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @mux/mux-node
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @mux/mux-node
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @mux/mux-node
  ```
  </Fragment>
</PackageManagerTabs>

### Mux 환경 API 액세스

API 토큰은 특정 Mux 환경에 연결됩니다. 이 환경은 기본적으로 동영상 및 관련 데이터를 담는 컨테이너 역할을 합니다. Mux에 가입하면 환경이 자동으로 생성됩니다. 추가 환경을 생성한 경우 토큰 생성 전에 올바른 환경을 선택해야 합니다. 이후 [ID 및 SECRET 토큰을 획득](https://www.mux.com/docs/core/stream-video-files#1-get-an-api-access-token)하여 Node SDK에 제공할 수 있습니다. 이 토큰들은 `.env` 파일에 저장된 환경 변수로 Astro 컴포넌트에 전달될 수 있습니다. 

이를 통해 동영상 정보 조회, 새 자산 생성, 메트릭 및 실시간 성능 확인 등을 위한 Mux Node SDK 인스턴스를 생성할 수 있습니다.

```astro title="src/components/StarlightVideo.astro"
---
import Mux from "@mux/mux-node";

const mux = new Mux ({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET,
})
---
```

<ReadMore>Astro 프로젝트에서 [환경 변수](/ko/guides/environment-variables/)를 사용하는 방법에 대해 자세히 알아보세요. 여기에는 Mux 자격 증명을 위한 [타입 안전 스키마](/ko/guides/environment-variables/#타입-안전-환경-변수) 생성도 포함됩니다.</ReadMore>

### 자산 데이터 조회하기

Astro 프로젝트에서 사용할 동영상 정보를 가져오려면 동영상의 `ASSET_ID` (Mux 대시보드에서 확인 가능)를 `retrieve()` 도우미 함수에 제공하세요. 이를 통해 동영상 제목이나 재생 시간과 같은 값을 Mux 컴포넌트와 HTML 템플릿에 전달할 수 있습니다.

```astro
---
import Mux from "@mux/mux-node";
import { MuxPlayer } from "@mux/mux-player-astro";

const mux = new Mux({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET,
})

const ASSET_ID = "E01irAaN8c6dk1010153uC2mzst7RVbAdJJWtHECAHFvDo";
const asset = await mux.video.assets.retrieve(ASSET_ID);

const playbackId = asset.playback_ids?.find((id)=> id.policy=== "public")?.id;
const videoTitle = asset?.meta?.title;
const createdAt = Number(asset?.created_at);
const duration = Number(asset?.duration)

const date = new Date(createdAt * 1000).toDateString()
const time = new Date(Math.round(duration) * 1000).toISOString().substring(14, 19)
---
<h1>내 동영상 페이지</h1>
<p>제목: {videoTitle}</p>
<p>등록 날짜: {date}</p>
<p>길이: {time}</p>

<MuxPlayer 
  playbackId={playbackId}
  metadata={{video_title: videoTitle}}
/>
```

[Mux Asset API 문서](https://www.mux.com/docs/api-reference/video/assets?utm_campaign=21819274-Astro&utm_source=astro-docs)에서 모든 자산 속성을 확인하세요.

## Mux Uploader

[Mux Uploader](https://www.mux.com/docs/guides/mux-uploader?utm_campaign=21819274-Astro&utm_source=astro-docs)는 Astro 웹사이트를 위한 완전한 기능을 갖춘 사용자 정의 가능한 동영상 업로드 UI입니다. 네이티브 Astro `<MuxUpload />` 컴포넌트를 사용하면 웹 애플리케이션에 동영상 업로드 기능을 구축할 수 있습니다.

Mux Uploader는 파일 업로드 시 수동 파일 선택과 드래그 앤 드롭 방식을 모두 지원하며, 업로드 일시 중지 및 재개 기능 등을 제공합니다.

### 설치하기

선호하는 패키지 관리자를 사용하여 Mux Uploader의 Astro 버전을 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @mux/mux-uploader-astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @mux/mux-uploader-astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @mux/mux-uploader-astro
  ```
  </Fragment>
</PackageManagerTabs>

### Mux에 동영상 업로드하기

동영상을 업로드하기 전에 [Mux API 액세스 토큰](#mux-환경-api-액세스)이 구성되어 있는지 확인하세요. 토큰이 구성되면 Mux Node SDK의 `create()` 함수를 사용하여 새 동영상 업로드를 시작할 수 있습니다.

```astro
---
import Layout from '../../layouts/Layout.astro';
import Mux from "@mux/mux-node";
import { MuxUploader } from "@mux/mux-uploader-astro";

const mux = new Mux({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET
});

const upload = await mux.video.uploads.create({
  new_asset_settings: {
    playback_policy: ['public'],
    video_quality: 'basic'
  },
  cors_origin: '*',
});
---
<Layout title="Mux에 동영상 업로드하기">
  <MuxUploader endpoint={upload.url} />
</Layout>
```

### 업로더 사용자 정의하기

추가 컴포넌트 속성을 사용하여 `<MuxUploader />`의 기능과 모양을 사용자 정의할 수 있습니다. 요소 스타일링 외에도, 다운로드 일시 중지 기능이나 최대 파일 크기 설정과 같은 옵션을 제어할 수 있습니다.

```astro
---
import { MuxUploader } from '@mux/mux-uploader-astro';
---

<MuxUploader
  endpoint="https://my-authenticated-url/storage?your-url-params"
  pausable
  maxFileSize={1000000000}
  chunkSize={8192}
  style={{
    '--progress-bar-fill-color': '#7e22ce',
    '--button-background-color': '#f0f0f0',
  }}
/>
```

추가 옵션은 [Mux Uploader 사용자 정의 가이드](https://www.mux.com/docs/guides/uploader-web-customize-look-and-feel?utm_campaign=21819274-Astro&utm_source=astro-docs)를 참조하세요.

### 업로드 이벤트 처리하기

Mux Uploader는 풍부한 기능과 미디어 업로드의 현재 상태에 따라 변화하는 동적 UI를 제공합니다. 업로더의 동작은 사용자 주도 이벤트 (예: 파일 선택, 오류 후 재시도)와 상태 주도 이벤트(예: 업로드 진행 중, 업로드 성공 완료) 모두에 반응합니다.

이러한 이벤트를 수신 대기하고 Astro 컴포넌트의 [클라이언트 측 스크립트](/ko/guides/client-side-scripts/)에서 처리할 수 있습니다. `MuxUploaderElement` 타입도 사용할 수 있습니다.

```astro
---
import { MuxUploader } from '@mux/mux-uploader-astro';
---

<MuxUploader
  id="my-uploader"
  endpoint="https://my-authenticated-url/storage?your-url-params"
  pausable
/>

<script>
  import type { MuxUploaderElement } from '@mux/mux-uploader-astro';
  
  const uploader = document.getElementById('my-uploader') as MuxUploaderElement;
  
  uploader.addEventListener('uploadstart', (event) => {
    console.log('업로드가 시작되었습니다!', event.detail);
  });
  
  uploader.addEventListener('success', (event) => {
    console.log('업로드가 성공적으로 완료되었습니다!', event.detail);
  });
  
  uploader.addEventListener('uploaderror', (event) => {
    console.error('업로드 중 오류가 발생했습니다!', event.detail);
  });
  
  uploader.addEventListener('progress', (event) => {
    console.log('업로드가 진행 중입니다: ', event.detail);
  });
</script>
```

## 공식 리소스

전체 API 및 웹훅 참조, 사용 가이드, CMS 통합, 맞춤형 비디오 워크플로 구축 등 추가 주제에 대한 정보는 다음을 참조하세요.

- [Astro용 공식 Mux 문서](https://www.mux.com/docs/integrations/astro?utm_campaign=21819274-Astro&utm_source=astro-docs)
- [`@mux/mux-player-astro` API 참조](https://github.com/muxinc/elements/blob/main/packages/mux-player-astro/README.md)
- [`@mux/mux-uploader-astro` API 참조](https://github.com/muxinc/elements/blob/main/packages/mux-uploader-astro/REFERENCE.md)
- [Mux와 Astro를 사용하여 동영상 업로더 구축하기 (YouTube)](https://www.youtube.com/watch?v=aaL1k5FsWfE)
- [Astro 업로더 및 플레이어 코드 예시 (GitHub)](https://github.com/muxinc/examples/tree/main/astro-uploader-and-player)
